Configuration

Code Scrawl is configured through json.

Docs

• Config File Locations
• Default Configs (with extensive comments)
• Alternate Setup

Config File Locations

Configs can be created at any of these locations:

• config/scrawl.json
• .config/scrawl.json
• .docsrc/scrawl.json
• scrawl.json (root of your project)

Default Configs

{  
  
    "--comments":{  
        "Documentation": "Visit https://www.taeluf.com/docs/Code%20Scrawl or https://gitlab.com/taeluf/php/CodeScrawl",  
        "Hopeful Changes": "I hope to  allow configuration of extensions from the scrawl config, and convert the PHP API generation to an extension. No promises."  
    },  
  
  
    "warning.deleteExistingDocs": false, "#a": "if true, files in `dir.docs` will be deleted before writing output. Regardless of this setting, same-named output files will be overwritten",  
    "warning.overwriteRootREADME": false, "#b": "true to copy the generated README from docs/README.md to the root README.md",  
  
    "markdown.fixNewLines": true, "#c": "true to add 2 spaces to the end of lines so that line breaks always display",  
    "markdown.prependNOEDIT": true, "#d": "true to add an HTML comment to the top of generated MD files telling you not to edit them",  
  
    "file.bootstrap":"scrawl-bootstrap.php", "#e": "(set false to disable) When scrawl is run, this file is executed before anything else. Fails silently if it doesn't exist. Configs are loaded before this is called. `$this` refers to the active \Tlf\Scrawl instance.",  
  
  
    "dir.docs": "docs", "#f": "The directory to output documentation files into. Same-named files WILL be overwritten",  
    "dir.src": "docsrc", "#g": "The directory containing your `.src.md` files",  
    "dir.templates": ["doctemplate"], "#h": "Array of directories containing `.md.php` that run PHP and output markdown. In the template files, `$this` is `\Tlf\Scrawl` instance and `$args` is the array of args passed to the @template(template_name, arg1, arg2) call.",  
    "dir.scan": ["src", "test"], "#i": "Directories containing code. Used by @export/@import, @note extension, @ast, and auto-generation of docs for PHP classes, and can be used by extensions",  
  
    "api.output_dir": "api/", "#j": "Set `false` to disable this feature. Directory WITHIN docs dir to output generated documentation of PHP classes found within the `dir.scan` directories.",  
    "api.generate_readme": true, "#k": "true to generate `docs/api/README.md` listing classes",  
  
    "#l": "Array of extension class names to load.",  
    "scrawl.extensions": [   
        "Tlf\\Scrawl\\Extension\\Notes"  
    ]  
  
}  

Note: Config keys have been updated June 9, 2025. All old config names will continue to work.

Alternate Setup

You can create your own bin script to execute Code Scrawl.

Example:

#!/usr/bin/env php  
<?php  
$scrawl = new \Tlf\Scrawl(array $options);  
$scrawl->file_bootstrap = 'scrawl-bootstrap.php'; // you can also set properties directly  
$scrawl->run();  

Then you can execute it with bin/my-scrawl-script (if the file is executable) or php bin/my-scrawl-script

For more information, look at the properties and constructor in Scrawl.php

Note: The keys are different when passing options this way than when using the built-in method to run Scrawl.